API Documentation with AI

The Documentation section for each API can now leverage our API Documentation Agent to generate a business overview, technical summary, or technical details from the API’s OpenAPI definition. You can generate new documentation, regenerate existing documentation, and manually edit the results, producing high-quality human and machine-readable content that is surfaced in the Developer Portal.

Prerequisites

• To generate documentation, the API must have a version and an OpenAPI specification file associated with it.

• AI Settings must be enabled in Control Plane by a Global admin user. To enable AI settings, go to Configuration > General. Read the linked Boomi AI Guidelines and select I have read and understand the Boomi AI Guidelines and agree to them.

  

  note

  For users with a Boomi sync tenant, AI must be enabled by a user with the Boomi Administrator role.

Create new documentation with AI

Follow these steps to create documentation using AI for your API.

1. In Control Plane, select APIs and select the API you want to create documentation for.

2. Select Documentation > Create New > Documentation.

   

3. In the Create New Documentation window, provide the following:

   • Documentation Name - Required name for the documentation.

   • Documentation Type - Markdown or Rich Text.

   • Welcome Page - If selected, the generated documentation is used on the Welcome page of the API in the Developer Portal.

   • Documentation with AI - When enabled, AI uses the OpenAPI specification for the API and creates one of the following types of documentation:

     tip

     For optimal performance, it is recommended to use a specification file of 3Mb or less. If your file is within the 3MB limit, it is still possible to get an error that is caused by a large path definition. A large path definition can cause the LLM to exceed the limit of tokens it can return while generating documentation. Some fields in a specification file that can contribute to large path definition errors are the summary, description, and example. Reducing the information contained in those fields will make the document generation possible.

     note

     The time it takes to generate the documentation depends on how large the specification file is. Generally, Business Overview documentation takes the least amount of time, and Technical Details takes the longest.

     • Business Overview - Describes the API business function, purpose, key inputs, and outcome.
     • Technical Summary - Describes the API key endpoints, common fields, headers and parameters, and common use cases.
     • Technical Details - Details of each API endpoint, including request schema/ headers, security, response schema/headers error handling, and examples.

     

     note

     If your API has multiple versions, the documentation is created from the latest version.

4. Select Create. The documentation is displayed in an editor. In the example below, the documentation is generated in Markdown format. You can edit the text in the left pane. The rendered text is visible in the right pane.

5. You can edit the documentation and select Save.

Regenerate documentation with AI

You can also use the Documentation with AI feature to regenerate existing API documentation into a business overview, technical summary, or technical details using AI. This option does not replace the existing documentation, but generates another type in addition to the existing documentation.

1. For any API that has documentation, go to APIs and select the API name.

2. Select Documentation.

3. Select the documentation that you want to regenerate with AI.

4. Select Regenerate Documentation.

5. Select the type of documentation to create and select Regenerate.

   

6. The documentation is displayed in an editor. You can edit the documentation and select Save.